# Time Picker Pro - User Guide
Time Picker Pro is a sleek dropdown time selector with powerful customization options and multiple output formats.

## Key Features

- **Multiple Time Formats**: 24-hour (23:30) and 12-hour (11:30 PM) display
- **Configurable Intervals**: 1, 5, 10, 15, 20, or 30-minute steps
- **Multiple Input Formats**: Accept time as HH:MM text, numeric (HHMM), or UNIX timestamps
- **Custom Styling**: Full control over appearance, colors, and spacing
- **Icon Support**: Add custom icons with spacing control

## Basic Setup

1. **Add Element**: Drag Time Picker Pro to your page
2. **Set Format**: Choose "24h" or "AM/PM" display
3. **Configure Interval**: Select minute step (1, 5, 10, 15, 20, 30)
4. **Customize Appearance**: Use styling options to match your design

## Configuration

### Core Settings

| Field | Options | Description |
|-------|---------|-------------|
| **Format** | "24h" or "AM/PM" | Display format for time |
| **Minute Step** | 1, 5, 10, 15, 20, 30 | Time interval options |
| **Placeholder** | Text | Custom placeholder (default: "Select time") |

### Initial Value Setup

Set initial time using any of these formats:

**Text Format (HH:MM)**
- `23:30` → Shows as 11:30 PM (AM/PM format)
- `14:15` → Shows as 2:15 PM (AM/PM format)
- `09:00` → Shows as 09:00 (24h format)

**Numeric Format (HHMM)**
- `2330` → Shows as 11:30 PM
- `1415` → Shows as 2:15 PM
- `900` → Shows as 9:00 AM

**UNIX Timestamp**
- `1756306800000` → Converts to local time
- `1756306800` → Supports 10 or 13-digit timestamps

### Visual Customization

**Icon Settings**
- **Icon URL**: Custom icon (16x16px recommended)
- **Icon Gap**: Space between icon and text (e.g., "8px", "12px")

**Layout**
- **Padding**: CSS-style padding (e.g., "8px 12px", "10px 15px 8px 20px")

**Dropdown Appearance**
- **Border Color**: Hex color (e.g., "#e5e7eb")
- **Border Width**: Thickness in pixels (e.g., 1, 2)
- **Border Radius**: Corner roundness (e.g., 6, 8)
- **Background Color**: Dropdown background (e.g., "#ffffff")
- **Divider Color**: Lines between options (e.g., "#f3f4f6")

## ⚠️ Important: Time Interval Alignment

**Your initial value must align with the selected minute step.**

**Correct Examples:**
- Minute Step 30: Valid times are 09:00, 09:30, 10:00, 10:30
- Minute Step 15: Valid times are 09:00, 09:15, 09:30, 09:45
- Minute Step 5: Valid times are 09:00, 09:05, 09:10, 09:15

**Incorrect Examples:**
- Minute Step 30: Invalid times are 09:15, 09:25, 09:35
- Minute Step 15: Invalid times are 09:07, 09:23, 09:37

*If initial value doesn't align with minute step, no time will be pre-selected.*

## Exposed States

Access these states in workflows and dynamic expressions:

| State | Type | Format | Example | Use Case |
|-------|------|--------|---------|----------|
| **as_string** | Text | HH:MM (24-hour) | "23:30", "14:15" | Database storage, API calls |
| **as_numeric** | Number | HHMM integer | 2330, 1415, 900 | Calculations, sorting |
| **as_unix** | Number | UNIX timestamp | 1756306800000 | Timezone handling, precise calculations |

## Workflow Integration

**Basic Usage:**
```
When TimePicker's as_string is not empty
→ Make changes to Current User
→ Set field "preferred_time" = TimePicker's as_string
```

**Reference States:**
- Use `TimePicker's as_string` for text operations
- Use `TimePicker's as_numeric` for calculations
- Use `TimePicker's as_unix` for timestamp operations

## Styling Integration

Time Picker Pro inherits Bubble's native styling:

- **Background**: Uses Bubble's background color setting
- **Text**: Applies Bubble's font color, size, and family
- **Borders**: Respects Bubble's border styling (unless overridden)
- **Responsive**: Adapts to Bubble's responsive settings

## Advanced Customization

### Custom Icon Implementation
```
Icon URL: https://your-domain.com/clock-icon.png
Icon Gap: 10px
Result: Icon appears 10px to the left of text
```

### CSS Padding Examples
- **Single value**: "12px" → 12px on all sides
- **Two values**: "8px 16px" → 8px top/bottom, 16px left/right
- **Four values**: "8px 12px 8px 16px" → top, right, bottom, left

## Troubleshooting

**Time not pre-selecting?**
- Verify initial value matches minute step interval
- Check time format is correct (HH:MM for text)
- Ensure UNIX timestamps are valid

**Dropdown not appearing?**
- Check for z-index conflicts
- Verify element has sufficient height
- Test without custom styling

**Styling not applying?**
- Bubble's native styles may override custom settings
- Use conditional formatting for advanced styling
- Verify color values are valid hex codes

## Browser Compatibility

- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+